Skip Headers

Oracle® Database JDBC Developer's Guide and Reference 10g Release 2 (10.2) Part Number B14355-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 7 Features Specific to JDBC OCI

This chapter introduces the features specific to the Java Database Connectivity (JDBC) Oracle Call Interface (OCI) driver. It also describes the OCI Instant Client. This chapter contains the following sections:

- OCI Connection Pooling

- Transparent Application Failover

- OCI Native XA

- OCI Instant Client

- Instant Client Light (English)

## OCI Connection Pooling

The OCI connection pooling feature is an Oracle-designed extension. The connection pooling provided by the JDBC OCI driver enables applications to have multiple logical connections, all of which are using a small set of physical connections. Each call on a logical connection is routed on to the physical connection that is available at the given time.

See Also: Chapter 26, "OCI Connection Pooling"

## Transparent Application Failover

The Transparent Application Failover feature of the JDBC OCI driver enables you to automatically reconnect to a database if the database instance to which the connection is made goes down. The new database connection, though created by a different node, is identical to the original.

See Also: Chapter 28, "Transparent Application Failover"

## OCI Native XA

The JDBC OCI driver also provides a feature called Native XA.

See Also: "OCI Native XA"

## OCI Instant Client

This section covers the following topics:

- Overview of Instant Client

- Benefits of Instant Client

- JDBC OCI Instant Client Installation Process

- Usage of Instant Client

- Patching Instant Client Shared Libraries

- Regeneration of Data Shared Library and ZIP files

- Database Connection Names for OCI Instant Client

- Environment Variables for OCI Instant Client

### Overview of Instant Client

The Instant Client feature makes it extremely easy to deploy OCI, Oracle C++ Call Interface (OCCI), Open Database Connectivity (ODBC), and JDBC-OCI based customer applications, by eliminating the need for an Oracle home. The storage space requirement of a JDBC OCI application running in the Instant Client mode is significantly reduced compared to the same application running on a full client-side installation. The Instant Client shared libraries occupy only about one-fourth the disk space used by a full client installation.

Table 7-1 shows the Oracle client-side files required to deploy a JDBC OCI application. Library names of release 10.2 are used in the table. The number part of library names will change in future releases to agree with the release.

Table 7-1 OCI Instant Client Shared Libraries

Linux and UNIX | Description for Linux and UNIX | Windows | Description for Windows
--- | --- | --- | ---
`libclnstsh.so.10.1` | Client Code Library | `oci.dll` | Forwarding functions that applications link with
`libociei.so` | OCI Instant Client Data Shared Library | `oraociei10.dll` | Data and code
`libnnz10.so` | Security Library | `orannzsbb10.dll` | Security Library
`libocijdbc10.so` | OCI Instant Client JDBC Library | `oraocijdbc10.dll` | OCI Instant Client JDBC Library
ALL JDBC Java Archive (JAR) files | See Also: "Checking the Environment Variables" | All JDBC JAR files | See Also: "Checking the Environment Variables"

Note: To provide Native XA functionality, you must copy the JDBC XA class library. On UNIX, this library, `libheteroxa10.so`, is located in `ORACLE_HOME``/jdbc/lib`. On Windows, this library, `heteroxa10.dll`, is located in `ORACLE_HOME``\bin`.

### Benefits of Instant Client

The benefits of Instant Client are:

- Installation involves copying a small number of files.

- The number of required files and the total disk storage on the Oracle client-side are significantly reduced.

- There is no loss of functionality or performance for applications deployed with the Instant Client.

- It is simple for independent software vendors to package applications.

### JDBC OCI Instant Client Installation Process

The Instant Client libraries can be installed by choosing the Instant Client option from the Oracle Universal Installer. The Instant Client libraries can also be downloaded from the Oracle Technology Network Web site. The installation process is as follows:

1. Download and install the Instant Client shared libraries and Oracle JDBC class libraries to a directory, such as `instantclient`.

2. Set the library path environment variable to the directory from step 1. For example, on UNIX, set `LD_LIBRARY_PATH` to `instantclient`. On Windows, set `PATH` to locate the `instantclient` directory.

3. Add the full pathnames of the JDBC class libraries to the `CLASSPATH` environment variable.

After completing these steps you are ready to run the JDBC OCI application.

The JDBC OCI application operates in the Instant Client mode when the OCI and JDBC shared libraries are accessible through the library path environment variable. In the Instant Client mode, there is no dependency on `ORACLE_HOME` and none of the other code and data files provided in `ORACLE_HOME` are needed by JDBC OCI, except for the `tnsnames.ora` file.

Instant Client can be also installed from the Oracle Universal Installer by selecting the Instant Client option. The installation should be done into an empty directory. As with the OTN install, you must set the `LD_LIBRARY_PATH` environment variable to the instant client directory to operate in the Instant Client mode.

If you have done a complete client installation by choosing the `Admin` option, then the Instant Client shared libraries are also installed. The location of the Instant Client shared libraries and JDBC class libraries in a full client installation is:

On Linux or UNIX:

- `libociei.so` library is in `$ORACLE_HOME/instantclient`

- `libclnstsh.so.10.1`, `libocijdbc10.so`, and `libnnz10.so` are in `$ORACLE_HOME/lib`

- The JDBC class libraries are in `$ORACLE_HOME/jdbc/lib`

On Windows:

- `oraociei10.dll` library is in `ORACLE_HOME\instantclient`

- `oci.dll`, `oraocijdbc10.dll`, and `orannzsbb10.dll` are in `ORACLE_HOME\bin`

- The JDBC class libraries are in `ORACLE_HOME\jdbc\lib`

By copying these files to a different directory, setting the library path to locate this directory, and adding the pathnames of the JDBC class libraries to `CLASSPATH`, you can enable running the JDBC OCI application in the Instant Client mode.

Notes: To provide Native XA functionality, you must copy the JDBC XA class library. On UNIX, this library, `libheteroxa10.so`, is located in `ORACLE_HOME``/jdbc/lib`. On Windows, this library, `heteroxa10.dll`, is located in `ORACLE_HOME``\bin`. All the libraries must be copied from the same `ORACLE_HOME` and must be placed in the same directory. On hybrid platforms, such as Sparc64, if the JDBC OCI driver needs to be operated in the Instant Client mode, then you must copy the `libociei.so` library from the `ORACLE_HOME``/instantclient32` directory. You must copy all other Sparc64 libraries needed for the JDBC OCI Instant Client from the `ORACLE_HOME``/lib32` directory. Only one set of Oracle libraries should be specified in the library path environment variable. That is, if you have multiple directories containing Instant Client libraries, then only one such directory should be specified in the library path environment variable. If you have an Oracle home on your computer, then you should not have the `ORACLE_HOME``/lib` and Instant Client directories in the library path environment variable simultaneously, regardless of the order in which they appear in the variable. That is, only one of `ORACLE_HOME``/lib` directory (for non-Instant Client operation) or Instant Client directory (for Instant Client operation) should be specified in the library path environment variable. Oracle recommends that you download Instant Client from Oracle Technology Network (OTN): `http://www.oracle.com/technology/tech/oci/instantclient/instantclient.html`

### Usage of Instant Client

Instant Client is a deployment feature and should be used for running production applications. For development, a full installation is necessary to access demonstration programs and so on. In general, all JDBC OCI functionality is available to an application being run in the Instant Client mode, except that the Instant Client mode is for client-side operation only. Therefore, server-side external procedures cannot operate in the Instant Client mode.

### Patching Instant Client Shared Libraries

Because Instant Client is a deployment feature, the emphasis has been on reducing the number and size of files required to run a JDBC OCI application. Therefore, all files needed to patch Instant Client shared libraries are not available in an Instant Client deployment. An `ORACLE_HOME` based full client installation is needed to patch the Instant Client shared libraries. The `opatch` utility will take care of patching the Instant Client shared libraries.

Note: On Microsoft Windows, you cannot patch the shared libraries.

After applying the patch in an `ORACLE_HOME` environment, copy the files listed in Table 7-1, "OCI Instant Client Shared Libraries" to the instant client directory as described in "JDBC OCI Instant Client Installation Process".

Instead of copying individual files, you can generate Instant Client ZIP files for OCI/OCCI, JDBC, and SQL*Plus as described in "Regeneration of Data Shared Library and ZIP files". Then, you can copy the ZIP files to the target computer and unzip them as described in "JDBC OCI Instant Client Installation Process".

The `opatch` utility stores the patching information of the `ORACLE_HOME` installation in `libclnstsh.so.10.1`. This information can be retrieved by the following command:

    genezi -v

Note that if the computer from where Instant Client is deployed does not have the `genezi` utility, then it must be copied from the `ORACLE_HOME``/bin` directory on the computer that has the `ORACLE_HOME` installation.

### Regeneration of Data Shared Library and ZIP files

The OCI Instant Client Data Shared Library, `libociei.so`, can be regenerated by performing the following steps in an Administrator Install of `ORACLE_HOME`:

    mkdir -p $ORACLE_HOME/rdbms/install/instantclient/light
    cd $ORACLE_HOME/rdbms/lib
    make -f ins_rdbms.mk ilibociei

A new version of `libociei.so` based on the current files in the `ORACLE_HOME` is then placed in the `ORACLE_HOME``/rdbms/install/instantclient` directory.

Note that the location of the regenerated Data Shared Library, `libociei.so`, is different from that of the original Data Shared Library, `libociei.so`, which is located in the `ORACLE_HOME``/instantclient` directory.The preceding steps also generate Instant Client ZIP files for OCI/OCCI, JDBC, and SQL*Plus.

Regeneration of data shared library and ZIP files is not available on Windows platforms.

### Database Connection Names for OCI Instant Client

All Oracle Net naming methods that do not require `ORACLE_HOME` or `TNS_ADMIN` to locate configuration files, such as `tnsnames.ora` or `sqlnet.ora`, work in the Instant Client mode. In particular, the connect string can be specified in the following formats:

- A Thin-style connect string of the form:

      host:port:service_name

  For example:

      url="jdbc:oracle:oci:@//example.com:5521:bjava21"

- A SQL Connect URL string of the form:

      //host:[port][/service name]

  For example:

      url="jdbc:oracle:oci:@//example.com:5521/bjava21

- As an Oracle Net keyword-value pair. For example:

      url="jdbc:oracle:oci:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)
        (HOST=dlsun242) (PORT=5521))
        (CONNECT_DATA=(SERVICE_NAME=bjava21)))"

Naming methods that require `TNS_ADMIN` to locate configuration files continue to work if the `TNS_ADMIN` environment variable is set.

See Also: Oracle Database Net Services Administrator's Guide for more information about connection formats

If the `TNS_ADMIN` environment variable is not set and `TNSNAMES` entries, such as `inst1`, are used, then the `ORACLE_HOME` environment variable must be set and the configuration files are expected to be in the `$ORACLE_HOME/network/admin` directory.

Note: In this case, the `ORACLE_HOME` environment variable is used only for locating Oracle Net configuration files. No other component of Client Code Library uses the value of the `ORACLE_HOME` environment variable.

The empty connect string is not supported. However, an alternate way to use the empty connect string is to set the `TWO_TASK` environment variable on UNIX, or the `LOCAL` variable on Windows, to either a `tnsnames.ora` entry or an Oracle Net keyword-value pair. If `TWO_TASK` or `LOCAL` is set to a `tnsnames.ora` entry, then the `tnsnames.ora` file must be loaded by the `TNS_ADMIN` or `ORACLE_HOME` setting.

Example

Consider that the `listener.ora` file on the database server contains the following information:

    LISTENER = (ADDRESS_LIST=(ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573)))

    SID_LIST_LISTENER = (SID_LIST=
                         (SID_DESC=(SID_NAME=rdbms3)
                         (GLOBAL_DBNAME=rdbms3.server6.us.alchemy.com)
                         (ORACLE_HOME=/home/dba/rdbms3/oracle)))

You can connect to this server in one of the following ways:

    url = "jdbc:oracle:oci:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)
                         (HOST=server6)(PORT=1573))
                         (CONNECT_DATA=(SERVICE_NAME=rdbms3.server6.us.alchemy.com)))"

or:

    url = "jdbc:oracle:oci:@//server6:1573/rdbms3.server6.us.alchemy.com"

Alternatively, you can set the `TWO_TASK` environment variable to any of the connect strings and connect to the database server without specifying the connect string along with the `sqlplus` command. For example, set the `TWO_TASK` environment in one of the following ways:

    setenv TWO_TASK "(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573))
                     (CONNECT_DATA=(SERVICE_NAME=rdbms3.server6.us.alchemy.com)))"

or:

    setenv TWO_TASK //server6:1573/rdbms3.server6.us.alchemy.com

Now, you can connect to the database server using the following URL:

    url = "jdbc:oracle:oci:@"

The connect string can also be stored in the `tnsnames.ora` file. For example, consider that the `tnsnames.ora` file contains the following:

    conn_str = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573))
                    (CONNECT_DATA=(SERVICE_NAME=rdbms3.server6.us.alchemy.com)))

If this `tnsnames.ora` file is located in the `/home/webuser/instantclient` directory, then you can set the `TNS_ADMIN` environment variable (or `LOCAL` on Microsoft Windows) as follows:

    setenv TNS_ADMIN /home/webuser/instantclient

Now, you can connect as follows:

    url = "jdbc:oracle:oci:@conn_str"

Note: The `TNS_ADMIN` environment variable specifies the directory where the `tnsnames.ora` file is located. However, `TNS_ADMIN` does not specify the full path of the `tnsnames.ora` file, instead it specifies the directory.

If this `tnsnames.ora` file is located in the `/network/server6/home/dba/oracle/network/admin` directory in the Oracle home, then instead of using `TNS_ADMIN` to locate the `tnsnames.ora` file, you can set the `ORACLE_HOME` environment variable as follows:

    setenv ORACLE_HOME /network/server6/home/dba/oracle

Now, you can connect with either of the `conn_str` connect string, as specified previously.

If `tnsnames.ora` can be located by `TNS_ADMIN` or `ORACLE_HOME`, then `TWO_TASK` can be set to:

    setenv TWO_TASK conn_str

You can then connect with the following URL:

    url = "jdbc:oracle:oci:@"

### Environment Variables for OCI Instant Client

The `ORACLE_HOME` environment variable no longer determines the location of the Globalization Support files and error message files. An OCI-only application does not require the `ORACLE_HOME` environment variable to be set. However, if the variable is set, then it does not have an impact on the operation of the OCI driver. OCI will always obtain its data from the Data Shared Library. If the Data Shared Library is not available, only then is the `ORACLE_HOME` environment variable used and a full client installation is assumed. Even though the `ORACLE_HOME` environment variable is not required to be set, if it is set, then it must be set to a valid operating system path name that identifies a directory.

Environment variables `ORA_NLS10` and `ORA_NLSPROFILES33` are ignored in the Instant Client mode.

In the Instant Client mode, if the `ORA_TZFILE` variable is not set, then the smaller, default, `timezone.dat` file from the Data Shared Library is used. If the larger `timezlrg.dat` file is to be used from the Data Shared Library, then set the `ORA_TZFILE` environment variable to the name of the file without any absolute or relative path names. That is:

On UNIX:

    setenv ORA_TZFILE timezlrg.dat

On Windows:

    set ORA_TZFILE timezlrg.dat

If the driver is not operating in the Instant Client mode, then the `ORA_TZFILE` variable, if set, names a complete path name, as it does in previous Oracle Database releases.

If `TNSNAMES` entries are used, then, as mentioned earlier, `TNS_ADMIN` directory must contain the `TNSNAMES` configuration files, and if `TNS_ADMIN` is not set, then the `ORACLE_HOME/network/admin` directory must contain Oracle Net Services configuration files.

## Instant Client Light (English)

The light weight version of Instant Client is called Instant Client Light (English). Instant Client Light is the short name. Instant Client Light is a significantly smaller version of Instant Client. This reduces the disk space requirements of the client installation by about 63 MB. This is achieved by the light weight data shared library, `libociicus.so` on UNIX platforms, which is 4 MB in size and a subset of the data shared library, `libociei.so`, which is 67 MB in size.

The light weight data shared library supports only a few character sets and error messages that are only in English. Therefore, the name Instant Client Light (English). Instant Client Light is designed for applications that require English-only error messages and use either US7ASCII, WE8DEC, or one of the Unicode character sets.

Table 7-2 lists the names of the data shared libraries for Instant Client and Instant Client Light (English) on different platforms. The table also specifies the size of each data shared library in parentheses following the library file name.

Table 7-2 Data Shared Library for Instant Client and Instant Client Light (English)

Platform | Instant Client | Instant Client Light (English)
--- | --- | ---
Sun Solaris | `libociei.so` (67 MB) | `libociicus.so` (4 MB)
Linux | `libociei.so` (67 MB) | `libociicus.so` (4 MB)
Microsoft Windows | `oraociei10.dll` (85 MB) | `oraociicus10.dll` (15 MB)

This section covers the following topics:

- Globalization Settings

- Operation

- Installation

### Globalization Settings

The `NLS_LANG` setting determines the language, territory, and character set as `language``_``territory``.``characterset`. In Instant Client Light, `language` can only be `American`, `territory` can be any that is supported, and `characterset` can be any one of the following:

- Single-byte

  - US7ASCII

  - WE8DEC

  - WE8MSWIN1252

  - WE8ISO8859P1

- Unicode

  - UTF8

  - AL16UTF16

  - AL32UTF8

Specifying character set or national character set other than those listed as the client or server character set or setting the language in `NLS_LANG` on the client will throw one of the following errors:

- `ORA-12734`

- `ORA-12735`

- `ORA-12736`

- `ORA-12737`

With Instant Client Light, the error messages obtained are only in English. Therefore, the valid values for the `NLS_LANG` setting are of the type:

    American_territory.characterset

where, `territory` can be any valid and supported territory and `characterset` can be any one the previously listed character sets.

Instant Client Light can operate with the OCI environment handles created in the OCI_UTF16 mode.

See Also: Oracle Database Globalization Support Guide for more information about NLS settings.

### Operation

To operate in the Instant Client Light mode, an application needs to set the `LD_LIBARARY_PATH` environment variable in UNIX or the `PATH` environment variable in Microsoft Windows to a location containing the client and data shared libraries. OCI applications by default look for the OCI data shared library, `libociei.so` in `LD_LIBRARY_PATH` in UNIX or `oraociei10.dll` in `PATH` in Microsoft Windows, to determine if the application should operate in the Instant Client mode. In case this library is not found, then OCI tries to load the Instant Client Light data shared library, `libociicus.so` in UNIX or `libociicus10.dll` in Microsoft Windows. If this library is found, then the application operates in the Instant Client Light mode. Otherwise, a non-Instant Client mode is assumed.

### Installation

Instant Client Light can be installed in one of the following ways:

- From OTN

  You can download the required file from:

  `http://www.oracle.com/technology/tech/oci/instantclient/instantclient.html`

  For Instant Client Light, instead of downloading and expanding the Basic package, download and unzip the Basic Light package. The `instantclient_10_2` directory in which the light weight libraries are unzipped should be empty before the unzip.

- From Client Admin Install

  Instead of copying `libociei.so` or `oraociei10.dll` from the `ORACLE_HOME``/instantclient directory`, copy `libociicus.so` or `oraociic10.dll` from the `ORACLE_HOME``/instantclient/light` directory. That is, the Instant Client directory on the `LD_LIBRARY_PATH`, in UNIX, should contain the Instant Client Light data shared library, `libociicus.so`, instead of the larger OCI Instant Client data shared library, `libociei.so`. In Microsoft Windows, `PATH` should contain `oraociicus10.dll` instead of `oraociei10.dll`.

- From Oracle Universal Installer

  If the Instant Client option is selected from the Oracle Universal Installer, then `libociei.so` (or `oraociei10.dll` on Microsoft Windows) is installed in the base directory of the installation which is going to be placed on `LD_LIBRARY_PATH`. This is so that Instant Client Light is not enabled by default. The Instant Client Light data shared library, `libociicus.so` (or `oraociicus10.dll` on Microsoft Windows), is installed in the `light` subdirectory of the base directory. Therefore, to operate in the Instant Client Light mode, the OCI data shared library, `libociei.so` (or `oraociei10.dll` on Windows) must be deleted or renamed and the Instant Client Light data shared library must be copied from the `light` subdirectory to the base directory of the installation.

  For example, if the Oracle Universal Installer has installed the Instant Client in `my_oraic_10_2` directory on `LD_LIBRARY_PATH`, then one would need to do the following to operate in the Instant Client Light mode.

      cd my_oraic_10_2
      rm libociei.so
      mv light/libociicus.so .

  Note: All the Instant Client files should be always copied or installed in an empty directory. This is to ensure that no incompatible binaries exist in the installation.